Table of Contents

Introduction

Modes and Configuration Options

Operation modes for different workload types

Installing driver and firmware for Intel GPUs

Pre-built Images

Installation

Install with NFD

Install with Operator

Verify Plugin Registration

Testing and Demos

Notes

Running GPU plugin as non-root

Labels created by GPU plugin

SR-IOV use with the plugin

KMD and UMD

Issues with media workloads on multi-GPU setups

Workaround for QSV and VA-API

Intel GPU plugin facilitates Kubernetes workload offloading by providing access to discrete (including Intel® Data Center GPU Flex & Max Series) and integrated Intel GPU devices supported by the host kernel.

Use cases include, but are not limited to:

Media transcode

Media analytics

Cloud gaming

High performance computing

AI training and inference

For example containers with Intel media driver (and components using that), can offload video transcoding operations, and containers with the Intel OpenCL / oneAPI Level Zero backend libraries can offload compute operations to GPU.

Intel GPU plugin may register four node resources to the Kubernetes cluster: | Resource | Description | |:—- |:——– | | gpu.intel.com/i915 | GPU instance running legacy i915 KMD | | gpu.intel.com/i915_monitoring | Monitoring resource for the legacy i915 KMD devices | | gpu.intel.com/xe | GPU instance running new xe KMD | | gpu.intel.com/xe_monitoring | Monitoring resource for the new xe KMD devices |

While GPU plugin basic operations support nodes having both (i915 and xe) KMDs on the same node, its resource management (=GAS) does not, for that node needs to have only one of the KMDs present.

For workloads on different KMDs, see KMD and UMD.

The plugin also accepts a number of other arguments (common to all plugins) related to logging. Please use the -h option to see the complete list of logging related options.

Intel GPU-plugin supports a few different operation modes. Depending on the workloads the cluster is running, some modes make more sense than others. Below is a table that explains the differences between the modes and suggests workload types for each mode. Mode selection applies to the whole GPU plugin deployment, so it is a cluster wide decision.

Note: Exclusive GPU usage with >=1000 millicores requires that also all other GPU containers specify (non-zero) millicores resource usage.

In case your host’s operating system lacks support for Intel GPUs, see this page for help: Drivers for Intel GPUs

Pre-built images of this component are available on the Docker hub. These images are automatically built and uploaded to the hub from the latest main branch of this repository.

Release tagged images of the components are also available on the Docker hub, tagged with their release version numbers in the format x.y.z, corresponding to the branches and releases in this repository.

See the development guide for details if you want to deploy a customized version of the plugin.

There are multiple ways to install Intel GPU plugin to a cluster. The most common methods are described below. For alternative methods, see advanced install page.

Note: Replace with the desired release tag or main to get devel images.

Note: Add --dry-run=client -o yaml to the kubectl commands below to visualize the yaml content being applied.

Deploy GPU plugin with the help of NFD (Node Feature Discovery). It detects the presence of Intel GPUs and labels them accordingly. GPU plugin’s node selector is used to deploy plugin to nodes which have such a GPU label.

GPU plugin can be installed with the Intel Device Plugin Operator. It allows configuring GPU plugin’s parameters without kustomizing the deployment files. The general installation is described in the install documentation. For configuring the GPU Custom Resource (CR), see the configuration options and operation modes.

GPU plugin can be installed alongside with GPU Aware Scheduling (GAS). It allows scheduling Pods which e.g. request only partial use of a GPU. The installation is described in fractional resources page.

You can verify that the plugin has been installed on the expected nodes by searching for the relevant resource allocation status on the nodes:

The GPU plugin functionality can be verified by deploying an OpenCL image which runs clinfo outputting the GPU capabilities (detected by driver installed to the image).

Make the image available to the cluster:

Build image:

Tag and push the intel-opencl-icd image to a repository available in the cluster. Then modify the intelgpu-job.yaml’s image location accordingly:

If you are running the demo on a single node cluster, and do not have your own registry, you can add image to node image cache instead. For example, to import docker image to containerd cache:

Create a job:

Review the job’s logs:

If the pod did not successfully launch, possibly because it could not obtain the requested GPU resource, it will be stuck in the Pending status:

This can be verified by checking the Events of the pod:

It is possible to run the GPU device plugin using a non-root user. To do this, the nodes’ DAC rules must be configured to device plugin socket creation and kubelet registration. Furthermore, the deployments securityContext must be configured with appropriate runAsUser/runAsGroup.

More info: https://kubernetes.io/blog/2021/11/09/non-root-containers-and-devices/

If installed with NFD and started with resource-management, plugin will export a set of labels for the node. For detailed info, see labeling documentation.

GPU plugin does not setup SR-IOV. It has to be configured by the cluster admin.

GPU plugin does however support provisioning Virtual Functions (VFs) to containers for a SR-IOV enabled GPU. When the plugin detects a GPU with SR-IOV VFs configured, it will only provision the VFs and leaves the PF device on the host.

There are 3 different Kernel Mode Drivers (KMD) available: i915 upstream, i915 backport and xe:

i915 upstream is a vanilla driver that comes from the upstream kernel and is included in the common Linux distributions, like Ubuntu.

i915 backport is an out-of-tree driver for older enterprise / LTS kernel versions, having better support for new HW before upstream kernel does. API it provides to user-space can differ from the eventual upstream version.

xe is a new KMD that is intended to support future GPUs. While it has experimental support for latest current GPUs (starting from Tigerlake), it will not support them officially.

For optimal performance, the KMD should be paired with the same UMD variant. When creating a workload container, depending on the target hardware, the UMD packages should be selected approriately.

NOTE: Xe UMD is in active development and should be considered as experimental.

Creating a workload that would support all the different KMDs is not currently possible. Below is a table that clarifies how each domain supports different KMDs.

OneVPL media API, 3D and compute APIs provide device discovery functionality for applications and work fine in multi-GPU setups. VA-API and legacy QSV (MediaSDK) media APIs do not, and do not provide (e.g. environment variable) override for their default device file.

As result, media applications using VA-API or QSV, fail to locate the correct GPU device file unless it is the first (”renderD128”) one, or device file name is explicitly specified with an application option.

Kubernetes device plugins expose only requested number of device files, and their naming matches host device file names (for several reasons unrelated to media). Therefore, on multi-GPU hosts, the only GPU device file mapped to the media container can differ from “renderD128”, and media applications using VA-API or QSV need to be explicitly told which one to use.

These options differ from application to application. Relevant FFmpeg options are documented here:

VA-API: https://trac.ffmpeg.org/wiki/Hardware/VAAPI

QSV: https://github.com/Intel-Media-SDK/MediaSDK/wiki/FFmpeg-QSV-Multi-GPU-Selection-on-Linux

Render device shell script locates and outputs the correct device file name. It can be added to the container and used to give device file name for the application.

Use it either from another script invoking the application, or directly from the Pod YAML command line. In latter case, it can be used either to add the device file name to the end of given command line, like this:

Or inline, like this:

If device file name is needed for multiple commands, one can use shell variable:

With argument N, script outputs name of the Nth suitable GPU device file, which can be used when more than one GPU resource was requested.